home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / uio.z / uio
Encoding:
Text File  |  2002-10-03  |  10.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. uuuuiiiioooo((((DDDD4444))))                                                                uuuuiiiioooo((((DDDD4444))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _uuuu_iiii_oooo - scatter/gather I/O request structure
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_uuuu_iiii_oooo_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      The _uuuu_iiii_oooo structure describes an I/O request that can be broken up into
  19.      different data storage areas (scatter/gather I/O).  A request is a list
  20.      of _iiii_oooo_vvvv_eeee_cccc(D4) structures (base/length pairs) indicating where in user
  21.      space or kernel space the data are to be read/written.
  22.  
  23. UUUUSSSSAAAAGGGGEEEE
  24.      The contents of the _uuuu_iiii_oooo structure passed to the driver through the entry
  25.      points in section D2 should not be changed directly by the driver.  The
  26.      _uuuu_iiii_oooo_mmmm_oooo_vvvv_eeee(D3), _uuuu_rrrr_eeee_aaaa_dddd_cccc(D3), and _uuuu_wwww_rrrr_iiii_tttt_eeee_cccc(D3) functions take care of
  27.      maintaining the _uuuu_iiii_oooo structure.  A block driver may also use the
  28.      _pppp_hhhh_yyyy_ssss_iiii_oooo_cccc_kkkk(D3) function to perform unbuffered I/O.  _pppp_hhhh_yyyy_ssss_iiii_oooo_cccc_kkkk also takes
  29.      care of maintaining the _uuuu_iiii_oooo structure.
  30.  
  31.      A driver that creates its own _uuuu_iiii_oooo structures for a data transfer is
  32.      responsible for zeroing it prior to initializing members accessible to
  33.      the driver.  The driver must not change the _uuuu_iiii_oooo structure afterwards; the
  34.      functions take care of maintaining the _uuuu_iiii_oooo structure.
  35.  
  36.      Note that a separate interface does not currently exist for allocating
  37.      _uuuu_iiii_oooo(D4) and _iiii_oooo_vvvv_eeee_cccc(D4) structures when the driver needs to create them
  38.      itself.  Therefore, the driver may either use _kkkk_mmmm_eeee_mmmm______zzzz_aaaa_llll_llll_oooo_cccc(D3) to allocate
  39.      them, or allocate them statically.
  40.  
  41.    SSSSttttrrrruuuuccccttttuuuurrrreeee DDDDeeeeffffiiiinnnniiiittttiiiioooonnnnssss
  42.      The _uuuu_iiii_oooo structure contains the following members:
  43.  
  44.      _iiii_oooo_vvvv_eeee_cccc______tttt  _****_uuuu_iiii_oooo______iiii_oooo_vvvv_;;;;    _////_**** _PPPP_oooo_iiii_nnnn_tttt_eeee_rrrr _tttt_oooo _tttt_hhhh_eeee _ssss_tttt_aaaa_rrrr_tttt _oooo_ffff _tttt_hhhh_eeee _iiii_oooo_vvvv_eeee_cccc _****_////
  45.                            _////_**** _aaaa_rrrr_rrrr_aaaa_yyyy _ffff_oooo_rrrr _tttt_hhhh_eeee _uuuu_iiii_oooo _ssss_tttt_rrrr_uuuu_cccc_tttt_uuuu_rrrr_eeee _****_////
  46.      _iiii_nnnn_tttt      _uuuu_iiii_oooo______iiii_oooo_vvvv_cccc_nnnn_tttt_;;;;  _////_**** _TTTT_hhhh_eeee _nnnn_uuuu_mmmm_bbbb_eeee_rrrr _oooo_ffff _iiii_oooo_vvvv_eeee_cccc_ssss _iiii_nnnn _tttt_hhhh_eeee _aaaa_rrrr_rrrr_aaaa_yyyy _****_////
  47.      _oooo_ffff_ffff______tttt    _uuuu_iiii_oooo______oooo_ffff_ffff_ssss_eeee_tttt_;;;;  _////_**** _OOOO_ffff_ffff_ssss_eeee_tttt _iiii_nnnn_tttt_oooo _ffff_iiii_llll_eeee _wwww_hhhh_eeee_rrrr_eeee _dddd_aaaa_tttt_aaaa _aaaa_rrrr_eeee _****_////
  48.                            _////_**** _tttt_rrrr_aaaa_nnnn_ssss_ffff_eeee_rrrr_rrrr_eeee_dddd _ffff_rrrr_oooo_mmmm _oooo_rrrr _tttt_oooo _****_////
  49.      _ssss_hhhh_oooo_rrrr_tttt    _uuuu_iiii_oooo______ssss_eeee_gggg_ffff_llll_gggg_;;;;  _////_**** _IIII_dddd_eeee_nnnn_tttt_iiii_ffff_iiii_eeee_ssss _tttt_hhhh_eeee _tttt_yyyy_pppp_eeee _oooo_ffff _IIII_////_OOOO _tttt_rrrr_aaaa_nnnn_ssss_ffff_eeee_rrrr _****_////
  50.      _ssss_hhhh_oooo_rrrr_tttt    _uuuu_iiii_oooo______ffff_mmmm_oooo_dddd_eeee_;;;;   _////_**** _FFFF_iiii_llll_eeee _mmmm_oooo_dddd_eeee _ffff_llll_aaaa_gggg_ssss _****_////
  51.      _iiii_nnnn_tttt      _uuuu_iiii_oooo______rrrr_eeee_ssss_iiii_dddd_;;;;   _////_**** _RRRR_eeee_ssss_iiii_dddd_uuuu_aaaa_llll _cccc_oooo_uuuu_nnnn_tttt _****_////
  52.  
  53.      The driver may only set _uuuu_iiii_oooo structure members to initialize them for a
  54.      data transfer for which the driver created the _uuuu_iiii_oooo structure.  The driver
  55.      must not otherwise change _uuuu_iiii_oooo structure members.  However, drivers may
  56.      read them.  The _uuuu_iiii_oooo structure members available for the driver to test or
  57.      set are described below:
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. uuuuiiiioooo((((DDDD4444))))                                                                uuuuiiiioooo((((DDDD4444))))
  71.  
  72.  
  73.  
  74.      _uuuu_iiii_oooo______iiii_oooo_vvvv contains a pointer to the _iiii_oooo_vvvv_eeee_cccc array for the _uuuu_iiii_oooo structure.  If
  75.      the driver creates a _uuuu_iiii_oooo structure for a data transfer, an associated
  76.      _iiii_oooo_vvvv_eeee_cccc array must also be created by the driver.
  77.  
  78.      _uuuu_iiii_oooo______iiii_oooo_vvvv_cccc_nnnn_tttt contains the number of elements in the _iiii_oooo_vvvv_eeee_cccc array for the _uuuu_iiii_oooo
  79.      structure.
  80.  
  81.      _uuuu_iiii_oooo______oooo_ffff_ffff_ssss_eeee_tttt contains the starting logical byte address on the device where
  82.      the data transfer is to occur.  Applicability of this field to the driver
  83.      is device-dependent.  It applies to randomly accessed devices, but may
  84.      not apply to all sequentially accessed devices.
  85.  
  86.      _uuuu_iiii_oooo______ssss_eeee_gggg_ffff_llll_gggg identifies the virtual address space in which the transfer
  87.      data areas reside.  The value _UUUU_IIII_OOOO______SSSS_YYYY_SSSS_SSSS_PPPP_AAAA_CCCC_EEEE indicates the data areas are
  88.      within kernel space.  The value _UUUU_IIII_OOOO______UUUU_SSSS_EEEE_RRRR_SSSS_PPPP_AAAA_CCCC_EEEE indicates one data area is
  89.      within kernel space and the other is within the user space of the current
  90.      process context.
  91.  
  92.      _uuuu_iiii_oooo______ffff_mmmm_oooo_dddd_eeee contains flags describing the file access mode for which the
  93.      data transfer is to occur.  Valid flags are:
  94.  
  95.      _FFFF_NNNN_DDDD_EEEE_LLLL_AAAA_YYYY           The driver should not wait if the requested data
  96.                        transfer cannot occur immediately; it should terminate
  97.                        the request without indicating an error occurred.  The
  98.                        driver's implementation of this flag's implied
  99.                        semantics are subject to device-dependent
  100.                        interpretation.
  101.  
  102.      _FFFF_NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK         The driver should not wait if the requested data
  103.                        transfer cannot occur immediately; it should terminate
  104.                        the request, returning the _EEEE_AAAA_GGGG_AAAA_IIII_NNNN error code as the
  105.                        completion status [see _eeee_rrrr_rrrr_nnnn_oooo_ssss(D5)].  The driver's
  106.                        implementation of the implied semantics of this flag
  107.                        are subject to device-dependent interpretation.
  108.  
  109.      If the driver creates a _uuuu_iiii_oooo structure for a data transfer, it may set the
  110.      flags described above in _uuuu_iiii_oooo______ffff_mmmm_oooo_dddd_eeee.
  111.  
  112.      _uuuu_iiii_oooo______rrrr_eeee_ssss_iiii_dddd indicates the number of bytes that have not been transferred to
  113.      or from the data area. If the driver creates a _uuuu_iiii_oooo structure for a data
  114.      transfer, _uuuu_iiii_oooo______rrrr_eeee_ssss_iiii_dddd is initialized by the driver as the number of bytes
  115.      to be transferred.  Note that a separate interface does not currently
  116.      exist for allocating a _uuuu_iiii_oooo structure.
  117.  
  118. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  119.      _iiii_oooo_vvvv_eeee_cccc(D4), _pppp_hhhh_yyyy_ssss_iiii_oooo_cccc_kkkk(D3), _rrrr_eeee_aaaa_dddd(D2), _uuuu_iiii_oooo_mmmm_oooo_vvvv_eeee(D3), _uuuu_rrrr_eeee_aaaa_dddd_cccc(D3), _uuuu_wwww_rrrr_iiii_tttt_eeee_cccc(D3),
  120.      _wwww_rrrr_iiii_tttt_eeee(D2)
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.